🐛 [v6] contributor-first: a relay in a disabled tier or with no matching work does not cover a lane - #17284

Summary

A contributor relay that the hub will not hand work to, or has no work for, still counted as covering its contributor-first lane, so the governor kept the resident agent's kicks withheld while nobody worked the lane. This is the same class of bug as #17233 (standby, quota hold) and #17268 (hourly/daily limit). With this change, RoleCoverage leaves out two more kinds of relay: one that is revoked or whose trust tier is in hub.disabled_tiers, and one that holds no task and has been answered no_matching_work (or repo_unmintable) for two minutes. The change is hub-side only. The relay is not touched.

What went wrong

• Disabled tier / revoked. Selection refuses a relay in a disabled tier with tier_disabled, and a resume is refused for a disabled tier or a revoked profile. The socket stays up and heartbeats, so RoleCoverage counted the relay anyway.
• No matching work. A relay whose every ready is answered no_matching_work is connected and idle. Seen live on 2026-11-08 on hive-wild-mole: the relay covered the scanner lane while selection answered no_matching_work every 30 seconds, so the resident scanner was withheld and nobody scanned.

Refs #17233, Refs #17268.

What changes

• One tier gate, shared. The revoked and disabled-tier rules move out of resumeGateReason into tierAccessGateReason(tier). Its disabled-tier half, tierDisabled(tier), is what fresh selection now calls; selection used to have its own copy of the disabled_tiers loop. resumeGateReason gives the same reasons in the same order as before: revoked outranks everything, and a disabled tier is reported after the hub checks. Selection's log line, decision text and tier_disabled reply are unchanged, and selection still does not check revoked, which is refused at auth. RoleCoverage copies the tier out under c.mu and calls tierAccessGateReason after h.mu is released, the same way the rate check works.
• An idle run on the connection. lastIdleReason already held the last task_unavailable reason. A new lastIdleReasonSince records when the current run of that reason began. no_matching_work and repo_unmintable count as one run, because the re-scan wrapper can rename one into the other with nothing changing.
  • Set by noteIdleReasonLocked, in the ready handler and in the yank/requeue reassignment path. Both already set lastIdleReason.
  • Cleared by clearIdleReasonLocked on every path that hands the relay work:
    • the selection commit, which covers issue, external, claim-preempt and operator-requeue assignments;
    • standby dispatch;
    • resume adoption on task_progress;
    • sendFixTask, the one place every fix-pr dispatch goes through.
• The window is 2 minutes, measured from the first empty answer. An idle relay re-asks 30 s after each task_unavailable (TASK_UNAVAILABLE_RETRY_MS), so this is about five empty answers in a row. One empty answer between two tasks never reaches it. The window is a time, not an answer count, so a relay that asks less often is judged on how long it has been idle. A longer window is not needed to stop flapping: the governor samples coverage once per evaluation (300 s by default), and a lane that drops out of the report is still withheld for contributor_first_grace (10 min by default). A relay that finds work again inside the grace keeps the lane without any resident kick.
• A busy relay still counts. That means a relay holding a primary task or any fix-pr task, as today.
• Docs.
  • The RoleCoverage comment and the "Contributor-first lanes" section of src/docs/agent-configuration.md now list every exclusion in one place.
  • The governor's contributor-first header names the two new exclusions.
  • One drifted line citation in agent-state-inventory.md is re-pointed.

Not changed: governor gate logic, relay code, and how often the relay retries. Other idle reasons (no_selected_work, capability_mismatch) are left as they were. They are worth a look in a follow-up.

Files

• src/pkg/dashboard/contribute_coverage.go: RoleCoverage, plus coverageNoWorkWindow and the idle-run helpers.
• src/pkg/dashboard/contribute_select.go: tierAccessGateReason / tierDisabled, used by resumeGateReason and selectTaskPass. Also clears the idle run on assignment.
• src/pkg/dashboard/contribute_ws.go: the lastIdleReasonSince field. Records the run in the ready and yank paths, and clears it on resume adoption.
• src/pkg/dashboard/contribute_fixqueue.go, contribute_standby_dispatch.go: clear the idle run.
• src/pkg/governor/contributor_first.go: header comment only.
• src/docs/agent-configuration.md, src/docs/design/agent-state-inventory.md, changelog.d/fixed-disabled-tier-no-work-relay-not-cover.md.

Tests

New tests in contribute_coverage_test.go. The no-work tests drive real handleReady over a socket, so the reasons come from real selection.

• The disabled-tier test also re-enables the tier and checks that the same relay covers again.
• The window test also hands the relay a task afterwards and checks that it covers while working the task and after the task ends.
• The one-answer test is a guard against dropping cover too early, so it cannot fail on the tip, which never drops cover.

Also ran go test ./pkg/dashboard/... ./pkg/governor/..., go vet, the docs citation and link checks, and the api-reference citation check.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1